ALMaSS  1.0
The Animal, Landscape and Man Simulation System
ALMaSS RoeDeer ODdox Documentation

Created by

Lene Jung Kjr
Department of Wildlife Ecology
Department of Bioscience, Aarhus University
Grenaavej 14
DK-8410 Roende

24th July 2012

A note about ODdox

ODdox documentation was created by combining a modified version of the ODD protocol ( Grimm et al. 2006) with documented code using doxygen (van Heesch, 1997) to create what we term ODdox documentation. The original ODD (Overview, Design, Detail) protocol divides the model documentation into defined sections covering aspects of model structure and functioning, and finally model details. The new ODdox protocol (Overview, Design, doxygen) broadly follows ODD protocol, but is completed and augmented by extracting comments from the source code. The details of the model are therefore described via descriptions of classes, methods, and variables using hyperlinks to the relevant sections in the source code. In contrast to the ODD, this means that by far the major part of the documentation is placed outside the traditional ODD sections, but linked to them via hyperlinks. The ODdox was specifically designed to facilitate documentation of large object-oriented models with many interacting components, and to provide a flexible way of building documentation as the software is developed. It is therefore structured following logical divisions of the model entities, primarily base class types. At each subdivision there is a class or set of linked classes in focus, and six of the seven ODD sections are written for these classes. The "Submodels" section of ODD becomes superfluous since any links to sub-models are covered by class descriptions for the classes in focus, and submodels per se should not exist. However, there may be important connections between the focus classes and other ODdox sections (e.g. other species, environment). A new section, "Interconnections", is used to describe these and provide html links to them. This approach permits the documentation of large models to be built as an expandable library, and rather than rewriting documentation for additions only requires judicious updating of the interconnection section, doxygen performs the rest of the tasks based on software comments in the new code. Our aim in developing ODdox was therefore to provide an easier, more complete, and more flexible method of documenting large models together with a more user friendly interface, benefitting developers and readers alike.


The model organism is the European roe deer (Capreolus capreolus) that occupies temperate agricultural landscapes representing a numerically large group of carabid beetles with common life-histories. We parameterised the model with data for Bembidion lampros Herbst (Carabidae), which is a Palearctic species that has been studied intensively as one of the most common beetles in European agroecosystems, and therefore has a well-described biology and natural history. The parameters are based on field and laboratory data on B. lampros from the literature. When necessary data were not available, we estimated parameters based on published data from other ground beetles with a similar life history.

1. Purpose

The RoeDeer model represents a typical group of flightless beetles and represents a species with limited dispersal power inhabiting the agricultural systems of norther temperate Europe. The main usage of this model is in evaluating impacts of human land management on a species of this type in terms particularly agricultural management and changes in landscape structure.

2. State variables and scales

2.a. State Variables

2.a.i Beetles

Beetle classes were based on Bembidion_Base, a class with the functionaility common to all beetles:
1) A variable containing the current beetle behavioural state: Bembidion_Base::CurrentBState
2) A pointer to the population manager: Bembidion_Base::m_OurPopulation
3) Attributes inherited from TAnimal, primarily location co-ordinates e.g. TAnimal::m_Location_x

Individual beetles had a set of common state variables each with its own value for the individual organism. These were:

Type of beetle:

Bembidion_Egg_List adds a single attribute to the base class attributes recording the day the egg was laid:

Bembidion_Larvae adds three attributes to the base class:
     Bembidion_Larvae::m_AgeDegrees recording the larval development in day degrees
     Bembidion_Larvae::m_LarvalStage being a record of the larval stage I-III
     Bembidion_Larvae::m_DayMade, as for the egg a record of the day the larva came into existance (egg hatch)

Bembidion_Pupae adds two attributes to the base class:
     Bembidion_Pupae::m_AgeDegrees recording the larval development in day degrees
     Bembidion_Pupae::m_DayMade, as for the egg and larvae, a record of the day the pupa came into existance (larval pupation)

Bembidion_Adult adds eight attributes to the base class:
     Bembidion_Adult::m_negDegrees is used to keep track of the number of negative day degrees experienced
     Bembidion_Adult::m_HibernateDegrees is used to keep track of the number of day degrees experienced in the spring which may trigger dispersal
     Bembidion_Adult::OldDirection is used to record the last direction moved
     Bembidion_Adult::m_EggCounter used to count the number of eggs produced
     Bembidion_Adult::m_CanReproduce used to signal reproductive readiness
     Bembidion_Adult::pList is a helper attribute when simulating movement
     Bembidion_Adult::pPoint is a helper attribute when simulating movement

2.a.ii Environment

ALMaSS is spatially explicit, requiring a detailed two-dimensional map of the landscape and having a time-step of 24 hours. The extent of the model landscape was variable and was a square raster representation of a landscape (e.g. 10 km x 10 km; 5 km x 5 km etc.) at 1 m2 resolution, with wrap around. State variables associated with each raster map were:
Id: Identification number associated with each unique polygon
Habitat: Land cover code for each polygon
Farm unit: If the land cover code was a field then it also had an owner associated with it. The owner represented the farmer who carried out farm management on their farm unit.
Vegetation Type - Vegetation type for the polygon (if any vegetation grows in the polygon.

The environment model in ALMaSS was weather dependent and the state variables associated with the weather sub-model were:
Temp: mean temperature on the given day (Celsius)
Wind: mean wind speed on the given day (m)
Rain: total precipitation on given day (mm)

ALMaSS is a complex ecological simulation system (Topping et al. 2003) with several sub-models, each with its unique set of state variables. E.g. Farm management is a crucial part of ALMaSS, consisting of 3 elements: farm units, farm types, and crop husbandry plans. There are 74 possible crops types in ALMaSS each with its own crop husbandry plan (e.g. WinterWheat) see Crop Classes. Each crop type is a sub-model and has its own set of state variables. Documentation of the environment section is an ongoing process but the classes indicated above provide useful starting points. Readers may refer to Topping et al. (2003) for more information on farm units, crop types, crop rotations, and farm types in ALMaSS.

3. Process overview and Scheduling

The model considers beetle behaviour of all four life stages on a daily basis together with data driven daily temperature and simulated changes in daily management of fields and the crops inside them by farmers.

Figure 1: Bembidion state diagram. NB All stages could transition to state Dying from any other behavioural state due to external messaging.

3.a Basic process for all beetle stages

The beetle life-stage classes are organised following a state-transition concept such that at any time each beetle object is in a specific behavioural given by the state variable Bembidion_Base::CurrentBState and exhibits behaviour associated with that state. As a result of this behaviour or external stimuli a transition may occur to another state. In the descriptions below, behavioural states are described together with some general functionality common to more that one life-stage. The first three methods (Begin_Step, Step and End_Step are an integral part of the scheduling carried out by the model, see Interconnections for more information.

3.a.i Begin Step: One of three structural controls within the each time-step of one day. The BeginStep was called once for each hare object in each time-step. When all objects had completed this step, the Step function was called. The BeginStep function was responsible for generating mortality and disturbance events, ageing and checking for physiological death. (See e.g. Bembidion_Adult::BeginStep)

3.a.ii Step: This function was responsible for calling the behavioural state code for each object. Each beetle object would have its Step function called at least once per time step. Each object in the list for that life stage would execute the Step function. This would result in a return parameter denoting the behavioural state the beetle was currently in together with a Boolean value to signal whether activity had been completed for that time step. If activity was not completed then Step would be called again on the next pass through the list. When all objects had finished the Step code, then the time step was completed for that beetle. (See e.g. Bembidion_Adult::Step)

3.a.iii Reproduction
Only beetles that are in preferred habitat (open agricultural fields) in spring may initiate reproduction. The rate of egg production f(egg) is temperature dependent and was calculated as:

f(egg) (T) = (T - T0) * C
T = temperature
T0 = lower threshold for egg production
C = egg production constant

Once Bembidion_All.cpp::cfg_TotalNoEggs eggs have been produced, the beetle stops egg production, and subsequently dies.

2.c.iv Development
Temperature dependent development was calculated for each developmental stage: egg, 1st, 2nd, 3rd instar and pupa based on data from Boye Jensen (1990). Development f(dev) was calculated as :

f(dev) (T) = T - T0 / L

T = temperature
T0 = lower threshold for development
L = duration of stage in day degrees

In order to save time the day degree calculations for each day are carried out globally (since temperature in uniform in space in our model).See Bembidion_Larvae::st_Develop & Bembidion_Population_Manager::DoFirst for details.

2.c.v Mortality
Beetles could die because they reached the end of their life span, from external events or due to density dependent factors (i.e. competition). External factors causing mortality were either farm operations, mainly soil cultivation techniques or temperature dependent winter mortality. The different cultivation methods were assigned different probabilities of beetle mortality, which were implemented when the farm operation in question occurred (see Farm management).
The resolution of the landscape model was 1m2. Density dependence was introduced by limiting the number of beetles that could be present on 3 x 3 m surrounding any beetle, to a fixed number of adults and larvae. Additional beetles were removed from the simulation (died, assumed eaten). Background mortality was implemented for the egg stage and the three larval instars. Beetles were assessed for density-dependent and background mortality once each simulation day. In order to avoid bias due to concurrency problems, the order of assessment of beetles was randomised once each time step. Special behaviours for Bembidion_Adult
The adult beetle starts life when it emerges from the pupa, most likely in the middle of a field. It then spends time foraging until late summer when aggregation behaviour is triggered and it will move towards field margins and other beetles. When it finds a suitable overwintering site, or when winter arrives the beetle enters hibernation. In spring the beetles come out of hibernation and disperse away from field boundaries and other beetles. During this time they will also lay eggs as they move. Once all the eggs are laid, or if the beetle lives to aggregation, then the beetle dies. This behaviour is modelled using the following methdods:

Bembidion_Adult::st_Forage - this is the basic behaviour when not aggregating or hibernating. This state calls Bembidion_Adult::DailyMovement.

Bembidion_Adult::DailyMovement is called whenever the beetle is not hibernating. It results if a call to Bembidion_Adult::MoveTo which carries out the actual movement and in turn calls Bembidion_Adult::CanReproduce.

Bembidion_Adult::CanReproduce determines the number of eggs produced and their locations along the path moved over the previous day. The number of eggs produced is also a function of temperature experienced see Bembidion_Population_Manager::DoFirst(). If all eggs are used up, then m_EggCounter becomes negative which ultimately kills the beetle in Bembidion_Adult::st_Aging. Eggs that are successfully laid enter the simualtion via a call to Bembidion_Adult::Reproduce.

Bembidion_Adult::st_Aggregate calls Bembidion_Adult::DailyMovement with the dispersal flag set as false, causing aggregative movement.
Bembidion_Adult::st_Hibernate accumulates day degrees from the beginning of the year and starts dispersal when the sum exceeds a threshold or at the beginning of March. At the end of hibernation the beetle is allowed to reproduce via the m_CanReproduce attribute.

Bembidion_Adult::Dispersal initiates the first call to Bembidion_Adult::DailyMovement resulting in subsequent calls to Bembidion_Adult::st_Forage.

3.b Scheduling

Beetle objects interact with each other and their environment during the simulation run. Since the time-step of the model is one day, this means that interactions need to be integrated into a single daily time-step. This gives rise to potential concurrency problems that were solved using a hierarchical structure to execution. This structure ensures that objects receive information and interact in a sensible order. This was particularly important in the case of lactating female hares who must first obtain enough energy to produce milk before the young are fed. Outside of the need for this kind of interaction control the order of execution of individual objects was random. Random execution order prevents the generation of bias between individuals, e.g. where the same individual would always obtain food first just by virtue of its position in a list of individuals (see Interconnections for more information).


4. Design Concepts

4.a Emergence

Emergent properties are patterns of population sizes and spatial distribution of beetles as a result of reproductive and dispersal procesess interacting with land management mortalities.

4.b. Adaptation

Adaptation is not used in the model.

4.c Fitness

Fitness is incorporated in terms of successful reproduction. In this version there is no genetic fitness concept only phenotypic stochasticity.

4.d Prediction

Prediction is not used in the Bembidion model.

4.e Sensing

Beetles can sense other beetles in close proximity of themselves (+/- 3m) and can sense the type and suitability of habitat in which they are in. Beetles can also sense the suitability of their current location for hibernation. Management induced mortality is also sensed by the beetle, although conceptually this is event driven in terms of implementation it is sensing (see e.g. Bembidion_Adult::OnFarmEvent).

4.f Interaction

Interactions between model beetles were primarily density-dependent mortalities
Interactions between beetles and their environment were on the basis of information flow from the environment to the beetle. The information content was of three types either (i) habitat type, vegetation structure (height and density), vegetation type, palatability, or (ii) it was information on management, e.g. if a field was cut for silage, or (iii) temperature data for development calculations. The first type of information was used in determining movement and feeding behaviour, the second resulted in a probabilistic mortality dependent upon life-stage and type of management. The third type was managed as at a higher hierarchical level by the Bembidion_Population_Manager which cicumvented the need for individual development calculations (see Interconnections for more information)

4.g Stochasticity

Stochasticity was used extensively within the model for applying probabilities primarily related to mortality and movement.

4.h Collectives

The class Bembidion_EggList is a collective used to optimse the code for speed by preventing multiple identical calculations of day degree changes.
All beetles were managed as lists of objects by the Bembidion_Population_Manager. This object was responsible for initiating daily activity for all beetles, and for output of population information as required.

4.i Observation

Since each beetle object is managed through the Bembidion_Population_Manager, it is relatively easy to extract information from a single individual, or any set of hares. Information is collected by writing C++ probes that simply sort through the list of beetles and extract information from those matching given criteria, e.g. output of the numbers of beetles within a certain area (see e.g. Population_Manager::Probe). Hence information is easily available at the population and individual level.

5. Initialisation

The model was initiated with a starting population of Bembidion_all.cpp::cfg_beetlestartnos adult beetles, each randomly placed on the landscape.

6. Inputs

Input parameters vary with each application of the ALMaSS partridge model but cover these basic types:
1) Landscape structure. Implemented as a GIS map, converted to ALMaSS data structures. Input fields consist of landscape element type (e.g. field, road, hedge) and extent.
2) Climate data on a daily basis. This data is looped if the simulation is longer than the data set. Data consists of mean daily temperature, daily precipitation and mean daily wind-speed.
3) Values for vole model parameters see tables 1 & 2.
4) Farming information this depends on the type and location of the farms being modelled and is implemented as a crop rotation and a set of management plans covering each crop used. These plans determine the timing and order of farm events, but these are in turn dependent on weather and farmers choices (both stochastic and mechanistic).
5) Other values related to specific application e.g. pesticide usage, toxicity, or timing of population crashes (e.g. see Partridge_Population_Manager::Catastrophe)
6) Specific ecological variables. These should be fixed during the parameterisation and fitting processes of model developement and ought not to be modified subsequently. Values are given by Table 1:

Table 1: Default parameters and sources for the Bembidion model.

7. Interconnections

Apart from connections to the Landscape, Farm and Crop classes, in common with all other ALMaSS models the beetle classes are administered by a population manager class, in this case Bembidion_Population_Manager. The Bembidion_Population_Manager is descended from Population_Manager and performs the role of an auditor in the simulation.

7.a The Beetle Population Manager

The population manager keeps track of individual beetle objects (eggs, larvae, pupae and adult females) in the model and initiates their daily behaviour via management of lists. The Population_Manager::Run method is the main daily behaviour control functions splitting each day into 5 steps as follows:

  1. At the start of each time step all hare objects within each list are randomised to avoid concurrency problems.
  2. After randomisation the BeginStep of each object in each list was called. Hierarchical execution started with the list of infant objects and ended with the execution of female objects.
  3. The Step function for each object in the same way as the BeginStep. The Step code of hares differs from BeginStep and EndStep in that it is repeatedly called by the population manager until all hares signal that they have finished Step behaviours for that day. This allows linking of behaviours and more flexibility in terms of daily activities.
  4. Any hare objects representing beetles that died or were redundent due to hatching or emergence were removed from the simulation and any output requests handled.

    Beetle objects created in the simulation during these steps were initiated by the population manager and their initial parameter values were set.

    Bembidion_Population_Manager is also responsible for precalcuation of many of the temperature or density-dependent pre-requisites for the simulation in Bembidion_Population_Manager::Init.
    In order to optimise speed, the locations of beetles are mapped using PositionMap ( Bembidion_Population_Manager::m_LarvaePosMap and Bembidion_Population_Manager::m_AdultPosMap) and updated constantly. These data constructs are used to rapidly determine local densities. Movement was optimised using a MovementMap data structure (Bembidion_Population_Manager::m_MoveMap) rather than interogate Landscape directly via interface methods.

    8. References

    Bilde, T., Axelsen, J.A. & S. Toft, 2000. The value of Collembola from agricultural soils as food for a generalist predator. Journal of Applied Ecology, 37: 672-683.
    Boye Jensen, L., 1990. Effects of temperature on the development of the immature stages of Bembidion lampros (Coleoptera: Carabidae). Entomophaga, 35: 277-281.
    Coombes, D.S. & N.W. Sotherton, 1986. The dispersal and distribution of polyphagous predatory Coleoptera in cereals. Annals of Applied Biology, 108: 461-474.
    Ekbom, B.S. & S. Wiktelius, 1985. Polyphagous arthropod predators in cereal crops in central Sweden, 1979-1982. Journal of Applied Entomology, 99: 433-442.
    Grimm, V., Berger, U., Bastiansen, F., Eliassen, S., Ginot, V., Giske, J., Goss-Custard, J., Grand, T., Heinz, S.K., Huse, G., Huth, A., Jepsen, J.U., Jorgensen, C., Mooij, W.M., Muller, B., Pe'er, G., Piou, C., Railsback, S.F., Robbins, A.M., Robbins, M.M., Rossmanith, E., Ruger, N., Strand, E., Souissi, S., Stillman, R.A., Vabo, R., Visser, U., & DeAngelis, D.L. (2006) A standard protocol for describing individual-based and agent-based models. Ecological Modelling, 198, 115-126.
    Hance, T. & C. Gregoire-Wibo, 1987. Effect of agricultural practices on carabid populations. Acta Phytopathologica et Entomologica Hungarica, 22: 147-160.
    Kromp, B., 1999. Carabid beetles in sustainable agriculture: a review on pest control efficacy, cultivation impacts and enhancement. Agriculture, Ecosystem and Environment, 74: 187-228.
    Kromp, B. & P. Meindl, 1997. Entomological Research in Organic Agriculture - Selected papers from the European Workshop on Entomological Research in Organic Agriculture, Austrian Federal Ministry of Science and Research, Vienna, March 1995. Biological Argriculture & Horticulture, 15: III-IV.
    Lys, J.A. & W. Nentwig. 1991. Surface activity of carabid beetles inhabiting cereal fields. Seasonal phenology and the influence of farming operations on five abundant species. Pedobiologia, 35: 129-138.
    Mitchell, B. 1963b. Ecology of two carabid beetles, Bembidion lampros (Herbst) and Trechus quadristriatus (Schrank) II. Studies on populations of adults in the field, with special reference to the technique of pitfall trapping. Journal of Animal Ecology, 32: 377-392.
    Petersen, M.K., 1997. Life histories of two predaceous beetles, Bembidion lampros and Tachyporus hypnorum, in the agroecosystem. Ph.D. thesis, Swedish University of Agricultural Sciences, Sweden.
    Petersen, M.K., Ekbom, B. & H.P. Ravn, 1996. Temperature dependent winter survival of Bembidion lampros and Tachyporus hypnorum. Journal of Insect Physiology, 42: 997-1005.
    Purvis, G., Carter, N. & W. Powell, 1988. Observations on the effects of an autumn application of a pyrethroid insecticide on non-target predatory species in winter cereals. Pages 153-166 in R. Cavarello and K.D. Sunderland (eds.). Integrated crop protection in cereals. A.A. Balkema. Rotterdam, Brookfield.
    Riedel, W. & T. Steenberg, 1998. Adult polyphagous coleopterans overwintering in cereal boundaries: winter mortality and susceptibility to the entomopathogenic fungus Beauveria bassiana. Biocontrol, 43: 175-188.
    Stinner, B.R. & G.J. House, 1990. Arthropods and other invertebrates in conservation-tillage agriculture. Annual Review of Entomology, 35: 299-318.
    Vickerman, G.P & K.D. Sunderland, 1977. Some effects of Dimethoate on arthropods in winter wheat. Journal of Applied Ecology, 14: 767-777.